using System;
using System.Security.Principal;
using System.Web;

namespace Sedna.Core.Security
{
	/// <summary>
	/// represents a particular mechanism of the underlying authentication
	/// should be used as a collaborator for login page, Global.asax to set up currently authenticated principal
	/// in the TopUserInfo control (via appropriate Action <see cref="LoginAuthenticateAction"/> 
	/// and <see cref="LogoutAction"/>) is used for logout.
	/// Although the design and implementation is FormBasedAuthentication schema oriented, 
	/// a particular instance of an IAuthenticator should not be aware of any authentication
	/// persistance mechanisms (such as cookies). Everything it has to do and be aware of is
	/// how to authenticate an IPrincipal via supplied username and a passowrd (or any other form of credentials).
	/// </summary>
	public interface IAuthenticator
	{
		/// <summary>
		/// tries to authenticate a principal with the specified 
		/// identity (such as username) and credentials (such as password)
		/// can throw any sort of Exception the underlying mechanism 
		/// thinks appropriate (including those native exceptions directly not supported by C#),
		/// thus a robust exception handling schema must be provided.
		/// </summary>
		/// <param name="userName">principal identity</param>
		/// <param name="credentials">principal password, must not be null or empty, - no guarantee that an underlying mechanism support it</param>
		/// <returns>
		/// an instance of a successfully authenticated principal 
		/// The method returns null if authentication fails.
		/// </returns>
		/// <remarks>
		/// Note that the returned IPrincipal is NOT installed in the current thread context, 
		/// thus a caller must set it in appropriate way.
		/// </remarks>
		IPrincipal Authenticate(string userName, string credentials);

		/// <summary>
		/// signes out a passed IPrincipal from the current context.
		/// </summary>
		/// <param name="principal">principal to be signed-out</param>
		void SignOut(IPrincipal principal);

        bool InjectPrincipal();

        bool InjectPrincipal(HttpContext context);

        bool InjectPrincipal(IPrincipal principal);

        bool InjectPrincipal(IPrincipal principal, HttpContext context);
	}
}
